Boss of Toys × WooCommerce

Czym jest ten system?

System Boss of Toys × WooCommerce to zautomatyzowany potok łączący hurtownię, sklep internetowy i kilka marketplace'ów w jeden spójny proces — od produktu w hurtowni, przez sklep i kanały sprzedaży, aż po dostawę do klienta i fakturę.

Architektura ogólna

KLIENCI / KANAŁY SPRZEDAŻY
  │
  ├─ Sklep WooCommerce (erotivo.pl, OVH) ── klient składa zamówienie
  ├─ Allegro (marketplace) ────────────────  kupujący składa zamówienie
  ├─ Empik (marketplace, Mirakl) ──────────  kupujący składa zamówienie
  └─ Ceneo Kup Teraz (marketplace) ────────  kupujący składa zamówienie
         │  (wszystkie trafiają jako zamówienia WooCommerce, z meta
         │   rozróżniającym pochodzenie — patrz rozdział "Przepływ zamówień")
         ▼
┌──────────────────────────────────────────────────────────┐
│     WordPress (OVH) — Plugin "BeeIntegro"                │
│     (katalog: wordpress-plugin/bossoftoys-manager/)       │
│                                                            │
│  Dashboard · Harmonogram · Ustawienia                     │
│  Boss Of Toys · Allegro (pełny panel, 9+ zakładek)         │
│  Logi · Meta box etykiet · Geowidget (checkout)            │
└─────────────────┬──────────────────────────────────────────┘
                  │ HTTP (X-API-Key)  ⚠ patrz uwaga niżej — nie HTTPS
                  ▼
┌──────────────────────────────────────────────────────────┐
│     VPS — Python FastAPI (port 8000, Docker)              │
│                                                            │
│  /api/jobs/*      /api/config/*     /api/labels/*         │
│  /api/allegro/*   /api/sse/*        /api/stats/*          │
│  /api/categories/* /api/returns/*   /api/logs/*           │
│  /api/metrics      /api/status      /health                │
│                                                            │
│  SQLite: data/api_bridge.db (WAL mode, 17 tabel)           │
└─────────────────┬──────────────────────────────────────────┘
                  │
                  ▼
┌──────────────────────────────────────────────────────────┐
│     Moduły core/ (47 plików Python, od 2026-07-20)          │
│                                                            │
│  10x BossOfToys/WooCommerce   18x Allegro                  │
│  6x Etykiety/logistyka        2x Fakturownia                │
│  1x Ceneo   2x Empik   8x infrastruktura wspólna (+own_stock)│
└─────────────────┬──────────────────────────────────────────┘
                  │
     ┌────────────┼────────────┬──────────────┬─────────────┐
     ▼            ▼            ▼              ▼             ▼
BossOfToys     WC REST      Allegro        ShipX/InPost   Fakturownia /
(hurtownia)    API          OAuth 2.0      REST API       Empik / Ceneo

Komunikacja między komponentami

Jak system rozpoznaje zamówienia z różnych kanałów

Nie ma osobnej bazy danych per kanał — wszystko jest zamówieniem WooCommerce. Kanał pochodzenia rozpoznawany jest po obecności konkretnego meta pola (szczegóły w rozdziale Przepływ zamówień i Meta WooCommerce):

Stos technologiczny

Backend (VPS)

Frontend (WordPress Plugin "BeeIntegro")

Wdrożenie i uruchomienie

Projekt działa na dwóch zupełnie oddzielnych infrastrukturach, wdrażanych i aktualizowanych niezależnie. Mylenie tych dwóch procedur jest częstym źródłem "poprawka nie działa po wdrożeniu" — patrz też rozdział Znane problemy, punkt 12.

A) VPS Linux/Docker — backend Python (`api/`, `core/`, `run_api.py`)

Użytkownik wgrywa pliki przez FileZilla/FTP na VPS, gdzie działają w kontenerze Docker.

# Uruchomienie bezpośrednio (bez kontenera, np. dev)
pip install -r requirements.txt
python run_api.py
python run_api.py --port 8080 --reload

# --- Produkcja: w Dockerze ---
docker compose up -d
docker compose logs -f
docker compose restart bossoftoys-api   # po zmianie pliku .py w api/ lub core/

• 1
  Zmiana pliku .py w api/ lub core/Wystarczy docker compose restart bossoftoys-api — wolumeny sprawiają, że kontener widzi nowy plik natychmiast.
• 2
  Zmiana samego docker-compose.ymlNowe wolumeny, porty, zmienne środowiskowe — wymaga pełnego odtworzenia: docker compose down && docker compose up -d. Sam restart NIE przeładuje nowej konfiguracji.
• 3
  "Update Image" w panelu hostingowym (np. aaPanel) ≠ wgranie koduTo najprawdopodobniej docker pull obrazu z rejestru — bezużyteczne dla bossoftoys-api:latest, który nigdzie nie jest wypchnięty (brak Dockerfile, brak CI). Nie traktuj tego przycisku jako sposobu wdrożenia kodu.
• 4
  Weryfikacja, że kontener czyta aktualny koddocker compose exec bossoftoys-api grep -n "unikalny fragment Twojej zmiany" /app/api/plik.py

B) WordPress plugin (`wordpress-plugin/bossoftoys-manager/`) — hosting OVH

Zupełnie osobna infrastruktura, zwykle też FTP, ale bez Dockera i bez restartu — PHP jest interpretowane na żywo.

• Skopiuj folder do wp-content/plugins/bossoftoys-manager/ i aktywuj w WordPress → Wtyczki (przy pierwszej instalacji).
• Zmiana pliku .php działa natychmiast po wgraniu — nie ma "restartu"/"kompilacji".
• Pułapka cache przeglądarki: wp_enqueue_script/wp_enqueue_style używają stałej BOT_VERSION jako ?ver=. Jeśli nie zbumpujesz tej stałej po zmianie dashboard.js/admin.css, przeglądarki użytkowników mogą serwować starą, zcache'owaną wersję mimo że plik na serwerze jest już nowy. Zawsze rób twardy refresh (Ctrl+Shift+R) po wdrożeniu zmian JS/CSS, zanim ocenisz wynik.

Minimalna konfiguracja `.env`

# WooCommerce
WOOCOMMERCE_URL=https://twojsklep.pl
WOOCOMMERCE_KEY=ck_xxxxxxxxxxxxxxxxxxxx
WOOCOMMERCE_SECRET=cs_xxxxxxxxxxxxxxxxxxxx

# WordPress REST API (media, produkty — wymaga Application Password)
WP_USERNAME=admin
WP_APP_PASSWORD=xxxx xxxx xxxx xxxx xxxx xxxx

# BossOfToys
BOSSOFTOYS_EMAIL=email@firma.pl
BOSSOFTOYS_PASSWORD=haslo
BOSSOFTOYS_ACRONYM=ESKL1_XXXX

# API security (klucz dla nagłówka X-API-Key)
API_SECRET_KEY=bardzo_dlugi_losowy_klucz_min_32_znaki

# Allegro OAuth
ALLEGRO_CLIENT_ID=twoj_client_id
ALLEGRO_CLIENT_SECRET=twoj_client_secret

# ShipX (InPost)
SHIPX_TOKEN=twoj_token_shipx
SHIPX_ORGANIZATION_ID=12345

# Fakturownia
FAKTUROWNIA_API_TOKEN=twoj_token
FAKTUROWNIA_DOMAIN=twojafirma

# Empik Marketplace
EMPIK_API_KEY=twoj_klucz_empik
EMPIK_SHOP_ID=twoj_shop_id

# Ceneo Kup Teraz
CENEO_API_KEY=twoj_klucz_ceneo

# Opcjonalne (AI, powiadomienia)
OPENAI_API_KEY=sk-xxxxxxxxxxxx
NTFY_TOPIC=twoj_temat_ntfy
SMTP_HOST=smtp.gmail.com
SMTP_USER=email@gmail.com
SMTP_PASSWORD=app_password
ALERT_EMAIL=odbiorca@gmail.com

Migracja na nowy serwer

• 1
  Skopiuj bazę danychPlik data/api_bridge.db — cały stan systemu: tokeny OAuth, historia zamówień, cache, profile cenowe.
• 2
  Skopiuj konfiguracjęKatalog config/ + plik .env.
• 3
  Uruchom serwerpython run_api.py (lub docker compose up -d) — migracje bazy uruchamiają się automatycznie przy starcie.

Konfiguracja

Priorytet ładowania (pierwszy wygrywa)

1. Zmienne środowiskowe procesu (export WOOCOMMERCE_URL=...)
2. Plik .env w katalogu głównym
3. Plik config/settings.json (tryb serwerowy — obecny)
4. Plik config/settings.dat (zaszyfrowany, relikt trybu Desktop — patrz pułapka MAC wyżej)

Sekcje konfiguracji

Harmonogram VPS — plik `config/scheduler.json`

Struktura pliku ma dwie części: jobs (moduły uruchamiane cyklicznie przez VPS Scheduler) i http_triggers (zewnętrzne wywołania HTTP GET do WordPressa, głównie dla Empika). Pełna, aktualna zawartość jobs — patrz rozdział Harmonogram CRON.

Baza danych SQLite

Plik: data/api_bridge.db — WAL mode + PRAGMA foreign_keys=ON. Cały trwały stan aplikacji żyje w jednym pliku.

Architektura dostępu do danych

core/*.py
   └─ from core.data_store import data_store   (import LOKALNY, wewnątrz funkcji!)
         └─ core/data_store.py (adapter)
               ├─ tryb serwerowy (VPS): api/repository.py → api/database.py → SQLite
               └─ fallback: pliki JSON (relikt trybu Desktop, dziś praktycznie nieużywany)

17 tabel bazy danych (stan zweryfikowany bezpośrednim zapytaniem SQL do żywej data/api_bridge.db, 2026-07-18)

Profile narzutów i przedziałów cenowych (nowość — `core/allegro_markup_profiles.py`)

Dwa niezależne mechanizmy cenowe, oba z dopasowaniem kategorii WooCommerce po prawdziwej hierarchii ID (rodzic/dziecko), nie po dopasowaniu tekstowym nazw:

• Profile narzutów (markup_profiles) — marża jako mnożnik ceny WC. Używane przez allegro_offer_sync.py (run), allegro_product_lister.py, allegro_scanner.py.
• Profile przedziałów cenowych (tier_profiles + tier_tables) — progi cena_hurtowa → narzut %, per kategoria. Używane przez allegro_offer_sync.py (run_apply_suggestions).

Gdy żaden profil danego typu nie jest aktywny, zachowanie jest w 100% zgodne z poprzednim, prostszym mechanizmem marż — zero ryzyka dla instalacji, które nie korzystają z tej funkcji.

Moduły — BossOfToys / WooCommerce

Szczegóły modułu Order Forwarder

Tryb auto_forward: jeśli boss_api.auto_forward=true, forwarding odbywa się inline po wygenerowaniu etykiety w label_auto_generator.py — bez potrzeby osobnego CRON-a Order Forwarder. Produkcyjny config/scheduler.json ma mimo to Order Forwarder włączony (co 15 min) jako niezależny mechanizm nadrabiający zamówienia, które z jakiegoś powodu ominęły ścieżkę auto-forward.

Własny towar / zwroty — moduł "Own Stock" (own_stock.py, nowość 2026-07-20)

Scenariusz biznesowy: klient odsyła oryginalnie zapakowany zwrot, sklep chce go odsprzedać wyłącznie we własnym sklepie (nie na Allegro). Produkt jest duplikowany natywną funkcją WooCommerce "Duplikuj", dostaje sztuczny SKU i EAN (nigdy nieobecne u dostawcy BossOfToys), i jest wystawiany z realną ilością posiadaną fizycznie.

• 1
  Checkbox na karcie produktuZakładka Zapasy, class-bot-own-stock.php → meta _own_stock_item = yes. Ilość sztuk pilnuje natywny WooCommerce stock (_manage_stock/_stock) — świadomie brak własnego licznika ilości.
• 2
  order_is_all_own_stock()Sprawdzana w order_forwarder_woo.py i inline w label_auto_generator.py: True tylko gdy WSZYSTKIE pozycje zamówienia mają flagę. Jeśli choć jedna pozycja nie jest własnym towarem — całe zamówienie idzie do BossOfToys normalnie (bez rozdzielania pozycji).
• 3
  DedupZamówienie oznaczane meta _own_stock_handled = 1 po pierwszym rozpoznaniu — kolejne cykle CRON nie odpytują ponownie WC o meta produktów.
• 4
  Ochrona przed skasowaniemproduct_deleter_woo.py wyklucza produkty z _own_stock_item=yes z ghost-trackingu — bez tego sztuczny SKU (nigdy nieobecny u dostawcy) zostałby po czasie usunięty razem ze zdjęciami.
• 5
  Widoczność dla sprzedawcyNTFY push ("Wyslij TY! Zamowienie #X") + badge 🏠 "Wysyłasz Ty" na liście zamówień WC (class-bot-order-list.php) + ostrzeżenie w meta boxie na stronie zamówienia (class-bot-order-meta.php) — trzy niezależne kanały.
• 6
  Filtr na liście produktówDropdown "Tylko własny towar" nad listą produktów WP (nowość 2026-07-21, class-bot-own-stock.php) — obok badge w kolumnie pozwala też odfiltrować widok do samych produktów oznaczonych _own_stock_item.

Moduły — Allegro Marketplace

18 plików w core/allegro_*.py — największy pojedynczy obszar integracji w projekcie. Wspólny klient (allegro_client.py) obsługuje OAuth 2.0 i dziesiątki metod REST; api/routes/allegro.py wystawia ok. 106 endpointów HTTP na bazie tych modułów.

• core/allegro_repricing.py — funkcjonalnie usunięty. Cała treść pliku to dziś def run(*args, **kwargs): raise RuntimeError(...) z komunikatem "Allegro zablokowało dostęp do API cen konkurencji na kontach produkcyjnych". Jeśli w panelu WordPress lub w starszych notatkach natrafisz na wzmiankę o module Repricing jako działającej funkcji analizy konkurencji — to nieaktualne. Endpoint POST /api/allegro/jobs/repricing może nadal istnieć w api/routes/allegro.py, ale wywoła ten sam błąd.
• core/allegro_invoice_upload.py ("Moduł do wysyłania faktur do Allegro") — funkcja upload_invoice_to_allegro() nie jest importowana z żadnego innego pliku .py w repo. Realny upload faktur do Allegro (przycisk "Wyślij fakturę" w panelu WP) idzie inną drogą: class-bot-admin.php::ajax_allegro_upload_invoice() woła bezpośrednio POST /api/allegro/orders/{id}/invoices, endpoint zaimplementowany wprost w api/routes/allegro.py, bez użycia tego modułu.

Ważne gotcha — Allegro API (raz odkryte, nie odkrywaj drugi raz)

Mapowanie statusów fulfillment

Moduły — Etykiety i Wysyłka

Label Auto Generator (CRON) — centralny moduł automatyzacji wysyłki

Plik: core/label_auto_generator.py.

Zamówienie "processing" bez etykiety
  │
  ├─ _allegro_checkout_id JEST     → Allegro Shipment Management API
  └─ _allegro_checkout_id BRAK     → ShipX (InPost) API

Po wygenerowaniu etykiety:
  ├─ Zapis PDF: data/labels/label_{order_id}.pdf
  ├─ Meta WC: _*_shipment_id, _*_tracking_number, _shipping_label_source
  ├─ Ceneo: jeśli zamówienie ma _ceneo_order_guid → SetOrderShipment (tracking)
  ├─ Empik: jeśli zamówienie ma _empik_order_id → OR23 (tracking) inline
  ├─ Pickup Scheduling (Allegro, inline, non-fatal błędy)
  ├─ Auto-forward do BossOfToys (jeśli auto_forward=true)
  └─ NTFY/e-mail przy błędach

3-krokowy flow Allegro (`allegro_label_generator.py`)

• 1
  POST /shipment-management/shipments/create-commandsTworzy przesyłkę z additionalProperties (np. InPost sendingMethod) i smart wymiarami paczki
• 2
  GET /shipment-management/shipments/create-commands/{id}Polling co 2s, max 30 prób — czeka na potwierdzenie
• 3a
  POST /shipment-management/labelPayload: {"shipmentIds": [...]} → zwraca labelId
• 3b
  GET /shipment-management/label/{labelId}Header: Accept: application/pdf — zwraca bajty PDF (używane, gdy krok 3a nie zwrócił PDF-a bezpośrednio; sam krok 3a woła Accept: application/octet-stream — patrz uwaga w tabeli pułapek Allegro wyżej)

Smart wymiary paczek InPost

System bierze największy gabaryt ze wszystkich produktów w zamówieniu. PHP hook (class-bot-inpost-sizes.php) kopiuje meta z produktu do line item przy składaniu zamówienia.

Pickup Scheduling (`allegro_pickup_scheduler.py`)

Shipment Tracking (`shipment_tracking.py`)

CRON co 120 min. Trzy źródła danych równolegle:

Zwroty przesyłek — moduł "Zwroty" (`return_pdf.py`, `api/routes/returns.py`)

Osobny, mniej udokumentowany w starszych materiałach podsystem: rejestruje zwroty/nieodebrane paczki w tabelach returned_shipments i return_notes, wystawia 5 endpointów w api/routes/returns.py. core/return_pdf.py generuje zbiorczy PDF ze zwrotami (fpdf2 + fonty NotoSans dla polskich znaków) jako dowód dla hurtowni BossOfToys. Wspierające skrypty w scripts/: backfill_returns.py, import_real_return.py, seed_test_return.py.

Moduły — Integracje zewnętrzne

Fakturownia.pl

Plik: core/fakturownia_client.py, core/fakturownia_lump_sum_fix.py.

• Produkty: Product Adder tworzy kartotekę (SKU, nazwa, cena, EAN) przy dodawaniu produktu.
• Faktury: PHP hook planuje pobranie PDF 60s po zmianie statusu zamówienia na processing.
• Pliki: wp-content/uploads/faktury/faktura_{order_id}.pdf. Auto-cleanup po 3 miesiącach.
• Jeśli zamówienie Allegro: faktura uploadowana do Allegro przez POST /api/allegro/orders/{id}/invoices (patrz uwaga o martwym module allegro_invoice_upload.py w rozdziale Allegro).
• Lump Sum Fix — CRON dzienny (days_back=7) korygujący faktury przy rozliczeniu ryczałtowym.

Empik Marketplace — OR23 i OR24 (Mirakl API)

Plik: core/empik_client.py, core/empik_price_sync.py.

Warunek automatycznego OR24: _empik_order_id JEST + _empik_carrier_tracking_number JEST + _empik_or24_sent BRAK + status WC = collected_from_sender LUB shipped/completed.

Import/eksport ofert i zamówień Empik odbywa się przez http_triggers w config/scheduler.json — VPS Scheduler cyklicznie odpytuje URL-e na erotivo.pl (action=export_offers, import_orders, export_products) zabezpieczone sekretem w query string, nie przez bezpośrednie wywołanie Pythona.

Ceneo Kup Teraz — integracja bez osobnego CRON-a

Plik: core/ceneo_client.py (klasa CeneoClient, BasketService + AuthorizationService).

W przeciwieństwie do Empika i Allegro, Ceneo nie ma własnego modułu importu zamówień ani osobnego wpisu w ModuleType/MODULE_MAP — logika jest wpleciona bezpośrednio w label_auto_generator.py i shipment_tracking.py, sterowana obecnością meta _ceneo_order_guid na zamówieniu WC. Token uwierzytelniający cache'owany z TTL ok. 2h (odświeżanie z zapasem 200s przed wygaśnięciem 7200s).

OpenAI — generowanie opisów

Dwa niezależne generatory, bo mają różne ograniczenia formatu docelowego:

• description_generator_woo.py — opisy sklepowe WooCommerce, HTML z inline stylami, modele gpt-4o-mini/gpt-4o.
• allegro_description_generator.py — opisy pod restrykcyjny zestaw dozwolonych tagów HTML Allegro (patrz rozdział Allegro).

Plugin WordPress — "BeeIntegro"

Plugin w interfejsie WordPress nazywa się BeeIntegro (nie "BossOfToys Manager" — to nazwa historyczna/wewnętrzna katalogu). Deployowany osobno od VPS/Dockera, zwykle FTP bezpośrednio do wp-content/plugins/bossoftoys-manager/ na hostingu OVH.

Struktura plików (stan 2026-07-20)

bossoftoys-manager/
├── bossoftoys-manager.php           # główny plik, require_once x11, stała BOT_VERSION (3.25.0)
├── readme.txt
├── includes/
│   ├── class-bot-api.php             (415 linii)  — komunikacja z VPS API (BOT_API)
│   ├── class-bot-admin.php          (3833 linie!) — menu, WSZYSTKIE 134 AJAX handlery,
│   │                                                 w tym cały backend UI Allegro
│   ├── class-bot-cron.php            (572 linie)  — WP-Cron (niezależny od VPS schedulera)
│   ├── class-bot-cache.php           (277 linii)  — cache WP Transients (BOT_Cache, TTL/typ)
│   ├── class-bot-allegro-orders.php  (385 linii)  — integracja zamówień Allegro z WC Orders
│   ├── class-bot-labels.php         (1062 linie)  — meta box etykiet na zamówieniu WC
│   ├── class-bot-geowidget.php       (366 linii)  — widget wyboru paczkomatu na checkout
│   ├── class-bot-inpost-sizes.php    (325 linii)  — gabaryty InPost per produkt
│   ├── class-bot-own-stock.php        (99 linii)  — NOWOŚĆ 2026-07-20: checkbox "własny towar"
│   │                                                 (zwroty) w zakładce Zapasy + kolumna produktów
│   ├── class-bot-order-meta.php      (222 linie)  — meta boxy (Ceneo GUID, InPost) + ostrzeżenie
│   │                                                 "wysyłasz Ty" (2026-07-20)
│   ├── class-bot-order-list.php      (248 linii)  — kolumny/filtry na liście zamówień WC + kolumna
│   │                                                 "Własny towar" (badge 🏠, 2026-07-20)
│   └── class-bot-ntfy.php            (130 linii)  — powiadomienia NTFY z poziomu WP
├── admin/
│   ├── views/
│   │   ├── dashboard.php             (603 linie)  — Dashboard ("BeeIntegro", bot-dashboard-4)
│   │   ├── page-allegro.php         (1555 linii!) — CAŁY panel Allegro (multi-tab)
│   │   ├── page-bossoftoys.php       (661 linii)  — panel hurtowni Boss Of Toys
│   │   ├── page-logs.php             (106 linii)  — przegląd logów systemowych
│   │   ├── schedule.php              (338 linii)  — harmonogram (UI WP-Cron + VPS scheduler)
│   │   └── settings.php              (709 linii)  — ustawienia (WooCommerce, BossOfToys, Allegro…)
│   ├── js/dashboard.js              (10414 linii!) — CAŁA logika JS (AJAX, wykresy, polling)
│   └── css/admin.css                 (7285 linii) — style
└── assets/
    ├── img/logo.png
    ├── css/geowidget.css
    └── js/geowidget.js

Menu w panelu WP

Top-level: BeeIntegro. Submenu (6 stron, każda osobny plik w admin/views/): Dashboard, Harmonogram, Ustawienia, Boss Of Toys, Allegro, Logi.

Wzorzec AJAX (do naśladowania przy nowych funkcjach)

• 1
  class-bot-api.phpMetoda wrapper wołająca $this->request('/api/...') (wzorzec: get_stats(), get_modules_list())
• 2
  class-bot-admin.php :: __construct()add_action('wp_ajax_bot_nazwa_akcji', array($this, 'ajax_nazwa_akcji'));
• 3
  class-bot-admin.php :: ajax_nazwa_akcji()check_ajax_referer('bot_ajax_nonce', 'nonce') → current_user_can('manage_woocommerce') → wywołanie BOT()->api->...() → wp_send_json_success/error
• 4
  dashboard.js (lub plik JS danej strony)$.ajax({url: botData.ajaxUrl, method: 'POST', data: {action: 'bot_nazwa_akcji', nonce: botData.nonce, ...}})

Dokładnie ten wzorzec posłużył do dodania funkcji "Podsumowanie błędów" 2026-07-18 (bot_get_error_digest → ajax_get_error_digest() → BOT_API::get_error_digest() → GET /api/logs/error-digest) — dobry, świeży przykład do skopiowania przy kolejnych dodatkach.

Cache (`class-bot-cache.php` / `BOT_Cache`)

WordPress Transients z TTL per typ danych: TTL_STATS=600s, TTL_ALLEGRO_STATS=900s, TTL_CONFIG=3600s, TTL_CATEGORIES=86400s, TTL_METRICS=1800s. Wzorzec użycia: BOT_Cache::get($key, function() { ...fetch... }, $ttl). Nie każdy handler musi z tego korzystać — np. "Podsumowanie błędów" świadomie NIE cache'uje, bo świeżość ważniejsza od wydajności przy debugowaniu.

Kluczowe hooki WooCommerce

Meta box etykiety (`class-bot-labels.php`)

Wyświetlany na stronie zamówienia WC. Zawiera:

• Status etykiety z kolorowym źródłem (🟠 Allegro / 🟡 ShipX)
• Kurier + numer tracking z linkiem śledzenia
• Przyciski: Generuj / Pobierz PDF / Regeneruj
• Badge statusu trackingu (zielony delivered, niebieski w transporcie, czerwony zwrot)
• Sekcja Empik: OR23 ✅/❌, OR24 ✅/❌, przycisk Wyślij OR24
• Sekcja Fakturownia: link do faktury PDF

Jak sprawdzić, czy lokalna kopia jest aktualna

wc -l wordpress-plugin/bossoftoys-manager/includes/class-bot-admin.php
# Oczekiwane: ~3800 linii. Jeśli wynik jest radykalnie mniejszy (np. ~500) —
# kopia lokalna jest nieaktualna. Zatrzymaj się i poproś użytkownika o świeże pliki
# zanim cokolwiek edytujesz — patrz incydent w rozdziale "Znane problemy", punkt 14.

API REST — mapa endpointów

Routery i skala endpointów (`api/server.py::include_router`)

Przykładowe, często używane endpointy

Uruchomienie i pierwsze kroki

• Domyślnie serwer nasłuchuje na 0.0.0.0:8000: python run_api.py (opcje: --port, --host, --reload)
• Dokumentacja interaktywna: http://host:8000/docs (Swagger) i /redoc
• Health check: http://host:8000/health
• Przy pierwszym uruchomieniu bez skonfigurowanego API_SECRET_KEY serwer wygeneruje i jednorazowo wyświetli w konsoli nowy klucz API — trzeba go zapisać, nie zostanie pokazany ponownie.

Przepływ zamówień

Jak system rozpoznaje typ zamówienia?

Meta zamówienia WC (sprawdzane w tej kolejności):
  ├─ _allegro_checkout_id JEST    → Zamówienie ALLEGRO
  │            Etykieta: Allegro Shipment Management
  │            Tracking: Allegro Tracking API
  │            Faktura: upload do Allegro
  │            Status: sync → Allegro SENT
  │
  ├─ _empik_order_id JEST         → Zamówienie EMPIK
  │            Etykieta: ShipX (InPost)
  │            OR23: numer trackingu do Empika (inline po etykiecie)
  │            OR24: potwierdzenie wysyłki (CRON shipment-tracking)
  │
  ├─ _ceneo_order_guid JEST       → Zamówienie CENEO KUP TERAZ
  │            Etykieta: ShipX (InPost)
  │            SetOrderShipment: numer trackingu (inline po etykiecie)
  │            SendOrder: potwierdzenie wysyłki (CRON shipment-tracking)
  │
  └─ Brak powyższych              → Zamówienie SKLEPOWE
               Etykieta: ShipX (InPost)
               Tracking: ShipX API
               Faktura: tylko lokalna (Fakturownia, bez uploadu do marketplace)

Zamówienie sklepowe — pełny flow

KROK 1 — ZŁOŻENIE
  Klient → WooCommerce → status: processing (po płatności)
  PHP hook → planuje pobranie faktury (60s)
  Geowidget → _inpost_point_id
  PHP hook → _inpost_parcel_size z produktów do line items

KROK 2 — ETYKIETA (CRON: label-generator, co 10 min)
  Brak _allegro_checkout_id → ShipX API
  Odczytuje _inpost_parcel_size → największy gabaryt
  Tworzy przesyłkę ShipX → PDF → data/labels/label_{id}.pdf
  Meta: _shipx_shipment_id, _shipx_tracking_number

  [auto_forward=true] → BossOfToys + status completed

KROK 3 — ŚLEDZENIE (CRON: shipment-tracking, co 120 min)
  ShipX API → status paczki
  "collected_from_sender" → AUTO-COMPLETE WC
  PHP hook (completed) → Fakturownia PDF

GOTOWE ✅

Zamówienie Allegro — pełny flow

KROK 1 — IMPORT (CRON: allegro-order-sync, co 10 min, hours_back=24)
  Allegro API → POST /wc/v3/orders
  Drugi PUT: _wc_order_attribution_utm_source="Allegro"
  Meta: _allegro_checkout_id, _allegro_buyer_*, _allegro_delivery_*
  PHP fix: zeruje VAT "zw" na wysyłce

KROK 2 — ETYKIETA (CRON: label-generator, co 10 min)
  Jest _allegro_checkout_id → Allegro Shipment Management
  3-krokowy flow: create → poll → label PDF
  Smart wymiary z _inpost_parcel_size
  Meta: _allegro_shipment_id, _allegro_tracking_number, _allegro_carrier
  Pickup scheduling: DHL → zamów, InPost/GLS/UPS → skip
  [auto_forward=true] → BossOfToys

KROK 3 — ŚLEDZENIE (CRON: shipment-tracking, co 120 min)
  Allegro Tracking API (/shipment-management/shipments/{id})
  statuses[-1] = najnowszy status
  IN_TRANSIT  → WC: "shipped"
  DELIVERED   → WC: "completed" → Fakturownia → upload faktury
              → Fulfillment sync: Allegro SENT

GOTOWE ✅

Zamówienie Empik

KROK 1 — IMPORT
  Empik (Mirakl) → WooCommerce przez http_trigger import_orders (meta _empik_order_id)

KROK 2 — ETYKIETA + OR23 (label-generator)
  ShipX etykieta → _shipx_shipment_id, _shipx_tracking_number
  OR23 inline: empik_client.send_tracking() → _empik_carrier_tracking_number

KROK 3 — OR24 (shipment-tracking, co 120 min)
  "collected_from_sender" + _empik_order_id + tracking + brak or24_sent
  → OR24: empik_client.confirm_ship() → Empik: SHIPPED
  → _empik_or24_sent = "1"
  (ręczny fallback: przycisk "Wyślij OR24")

GOTOWE ✅

Zamówienie Ceneo Kup Teraz

KROK 1 — IMPORT
  Zamówienie trafia do WC z meta _ceneo_order_guid (mechanizm importu
  poza core/ — sprawdź WP plugin/zewnętrzną integrację, jeśli to zadanie dotyczy)

KROK 2 — ETYKIETA + SetOrderShipment (label-generator, inline)
  ShipX etykieta → _shipx_shipment_id, _shipx_tracking_number
  SetOrderShipment inline: ceneo_client.CeneoClient(...).set_order_shipment()
  → _ceneo_tracking_sent

KROK 3 — SendOrder (shipment-tracking, co 120 min, inline)
  "collected_from_sender" + _ceneo_order_guid + brak _ceneo_send_order_sent
  → SendOrder → _ceneo_send_order_sent

GOTOWE ✅

Harmonogram CRON

Zawartość zweryfikowana bezpośrednio w config/scheduler.json produkcyjnym (2026-07-18). Wszystkie zadania jobs są dziś enabled: true.

Zewnętrzne wyzwalacze HTTP (`http_triggers`)

Osobna sekcja w config/scheduler.json — VPS Scheduler cyklicznie wywołuje GET-y do WordPressa (nie do własnego API), głównie dla integracji Empik przez wtyczkę empik-for-woocommerce: eksport ofert (co 30 min), import zamówień (co 10 min), eksport produktów (co 24h). URL-e zawierają sekret w query string — patrz ostrzeżenie w rozdziale Konfiguracja.

Kolejność włączania (nowe wdrożenie)

• 1
  Etykiety i śledzenieLabel Generator + Shipment Tracking + Order Forwarder (lub auto_forward=true)
• 2
  Import zamówień z marketplace'ówAllegro Order Sync + Allegro Offer Sync; import Empik/Ceneo wg ich własnych mechanizmów
• 3
  ProduktyStock Sync + Price Updater + Product Adder (najpierw raz ręcznie)
• 4
  Product DeleterNajpierw ręcznie z dry_run=true przez kilka dni, sprawdź logi, dopiero potem realne usuwanie

Meta dane na zamówieniach WooCommerce

Kluczowe meta (routing systemu)

Meta produktu (nie zamówienia) sterujące tym mechanizmem: _own_stock_item = yes/no, checkbox w zakładce Zapasy karty produktu. Szczegóły: rozdział Moduły — BossOfToys / WooCommerce, sekcja "Własny towar / zwroty".

Meta etykiet Allegro

Meta etykiet ShipX

Meta Empik

Meta Ceneo

Meta Attribution (Pochodzenie w WC)

Zależności między modułami

BossOfToys API / XML
        │
        ├──────────────────────────────────┐
        ▼                                 ▼
  Stock Sync ──────────► WooCommerce    Product Adder
  Price Updater ─────────► (REST API)   Product Deleter
  Cost Backfill                │
                               │
        ┌──────────────────────┤
        │                      │
        ▼                      ▼
  Allegro Scanner ──► WooCommerce produkty (EAN)
        │
        ▼
  Allegro Lister ──────────► Allegro API (OAuth 2.0)
                                     │
        ┌────────────────────────────┤
        │                            │
        ▼                            ▼
  Allegro Order Sync          Allegro Offer Sync
        │                       (+ Markup/Tier Profiles)
        ▼                            │
  WooCommerce                        ▼
  (zamówienia,               Allegro oferty
   + Empik/Ceneo             (stany/ceny)
   przez własne wejścia)
        │
        ├──────────────────────────────────────┐
        │                                      │
        ▼                                      ▼
  Label Auto Generator                   Order Forwarder
    │      │      │                            │
    │      │      │                            ▼
    ▼      ▼      ▼                     BossOfToys API
  ShipX  Allegro  inline OR23/          (zamówienie + PDF)
  Label  Label    SetOrderShipment
    │      │      (Empik / Ceneo)
    └──┬───┘
       │
       ▼
  Shipment Tracking ──► ShipX API / Allegro Tracking API
       │
       ├──────────────► AUTO-COMPLETE WC
       ├──────────────► OR24 Empik / SendOrder Ceneo (inline, jeśli meta obecne)
       └──────────────► Fakturownia → upload faktury → Allegro SENT

Kolejność uruchamiania modułów

1. Label Generator — etykiety muszą być pierwsze (dla wszystkich kanałów)
2. Shipment Tracking — śledzi i auto-complete/OR24/SendOrder
3. Order Forwarder — wymaga istniejącej etykiety
4. Allegro Order Sync — import nowych zamówień
5. Stock Sync — stany magazynowe
6. Allegro Offer Sync — po sync stanów
7. Price Updater — ceny
8. Allegro Fulfillment Sync — na końcu (zależy od etykiet i statusów)

Bezpieczeństwo

Ten rozdział konsoliduje ustalenia bezpieczeństwa z .claude/SECURITY_SETUP.md (historyczny opis Windows Server) i audytu kodu z 2026-07-17/18. Koncepcja "dwuwarstwowego zabezpieczenia" (VPN mesh + whitelist IP) jest nadal dobrą praktyką, ale jej konkretna implementacja opisana w starym dokumencie dotyczy poprzedniego serwera Windows i wymaga potwierdzenia na obecnym VPS Linux.

Model sieciowy — do zweryfikowania na obecnym VPS

• Historycznie: Tailscale (mesh VPN, WireGuard) dla dostępu administracyjnego + Windows Firewall whitelist IP dla dostępu z serwera WooCommerce. Tailscale działa też natywnie na Linuksie (tailscaled + systemd) — jeśli nadal jest używany, komendy typu tailscale status działają identycznie.
• docker-compose.yml publikuje port 8000:8000, co domyślnie wystawia port na wszystkich interfejsach hosta, o ile firewall hosta lub reverse proxy tego nie ogranicza. Nie zakładaj, że ochrona nadal działa tak samo jak w opisie Windows — zweryfikuj z użytkownikiem aktualną konfigurację firewalla/reverse proxy na obecnym VPS przed poleganiem na tym modelu.
• Skrypty PowerShell (firewall_setup.ps1, firewall_rollback.ps1, firewall_add_ip.ps1) opisane w starym dokumencie nie istnieją już w repo — albo świadomie usunięte przy migracji, albo nigdy nie trafiły do tego katalogu roboczego.

Znane, potwierdzone ryzyka

Autoryzacja API

• Wszystkie endpointy poza /health i / wymagają nagłówka X-API-Key zgodnego z API_SECRET_KEY z .env.
• Tokeny OAuth Allegro żyją w SQLite (kv_store), nie w plikach configu — nie sprawdzaj obecności access_token w configu jako testu autoryzacji, tylko client_id/client_secret.
• http_triggers w config/scheduler.json (integracja Empik) używają sekretu wprost w query string URL — traktuj te URL-e jak hasło, nigdy nie wklejaj ich do dokumentów/logów/zgłoszeń.

Znane problemy i ryzyka

Skonsolidowana lista z .claude/KNOWN_ISSUES.md (stan 2026-07-18) — nie jest to lista potwierdzonych, aktualnie trwających awarii, tylko udokumentowanych ryzyk i incydentów z pełną historią diagnozy. Pełne szczegóły techniczne (dowody, dokładne linie kodu) w źródłowym pliku.

Historia wersji

Rozwiązywanie problemów

Diagnoza ogólna — pierwsze kroki

1. Sprawdź logi VPS: WordPress → BeeIntegro → Logi, albo sekcję "Podsumowanie błędów" na Dashboardzie
2. Status API Allegro: GET /api/allegro/status
3. Diagnostyka WP REST API: GET /api/config/wp/test
4. Status Schedulera: GET /api/stats/scheduler
5. Zweryfikuj, że kontener faktycznie widzi aktualny kod: docker compose exec bossoftoys-api grep -n "fragment zmiany" /app/api/plik.py
6. Weryfikacja składni: python -m py_compile core/nazwa_modulu.py

Allegro

Brak tokenu / "Nie połączono z Allegro"

Sprawdź czy ALLEGRO_CLIENT_ID i ALLEGRO_CLIENT_SECRET są w .env. Tokeny OAuth są w SQLite (kv_store), nie w configu — autoryzuj przez WordPress → Ustawienia → Allegro.

Zamówienia Allegro — "Pochodzenie: Nieznane"

Wymaga obu meta: _wc_order_attribution_utm_source="Allegro" ORAZ _wc_order_attribution_source_type="utm". WooCommerce może nadpisać attribution w swoim hooku — allegro_order_sync.py wykonuje drugi PUT po zapisie zamówienia właśnie z tego powodu.

Moduł Repricing zwraca błąd/wyjątek

To oczekiwane — core/allegro_repricing.py jest dziś funkcjonalnie usunięty (rzuca RuntimeError) po tym jak Allegro zablokowało dostęp do API cen konkurencji na kontach produkcyjnych. To nie jest bug do naprawienia.

Błąd 406 przy pobieraniu etykiety

Header Accept: application/octet-stream jest wymagany (NIE application/pdf!).

Endpoint etykiety 404

/shipment-management/label/commands NIE ISTNIEJE. Używaj POST /shipment-management/label.

WooCommerce / WordPress

Empik / Ceneo

Baza danych

Komendy diagnostyczne

# Weryfikacja składni Pythona
python -m py_compile core/allegro_order_sync.py

# Test połączenia Allegro
curl -H "X-API-Key: TWOJ_KLUCZ" http://vps:8000/api/allegro/status

# Test połączenia WordPress
curl -H "X-API-Key: TWOJ_KLUCZ" http://vps:8000/api/config/wp/test

# Status Schedulera VPS
curl -H "X-API-Key: TWOJ_KLUCZ" http://vps:8000/api/stats/scheduler

# Podsumowanie błędów per moduł (dodane 2026-07-18)
curl -H "X-API-Key: TWOJ_KLUCZ" http://vps:8000/api/logs/error-digest

# Weryfikacja, że kontener widzi aktualny kod z wolumenu
docker compose exec bossoftoys-api grep -n "fragment" /app/api/plik.py

# Rozmiar pluginu WP — test świeżości lokalnej kopii
wc -l wordpress-plugin/bossoftoys-manager/includes/class-bot-admin.php

Zasady pracy nad kodem (dla programistów)

Ten projekt ma dojrzałe, spójne konwencje — poniższe zasady dotyczą pracy nad core/, api/ i wordpress-plugin/. Zebrane z .claude/skills/erotivo-dev/ i preferencji zapisanych w .claude/CLAUDE.md.

Twarde zasady projektu

• Polski język — komunikaty logów, komentarze, teksty UI po polsku.
• Stabilność ponad prędkość — długie timeouty, mniejsze batche, retry z backoff zamiast agresywnej równoległości.
• DRY-RUN domyślnie dla operacji destrukcyjnych (usuwanie produktów, przekazywanie zamówień). Nie usuwaj/nie osłabiaj trybu dry-run bez wyraźnej prośby.
• Nigdy nie commituj .env, config/settings.dat, config/api_key.txt, data/ — sekrety i dane runtime.
• Weryfikacja składni Python: python -m py_compile core/plik.py — nie ma testów jednostkowych w repo, to jedyna sieć bezpieczeństwa składniowa przed wdrożeniem.
• Weryfikacja PHP: php -l plik.php (jeśli PHP dostępne lokalnie; jeśli nie — policz nawiasy klamrowe ręcznie). Dla JS: node --check plik.js.

Wzorzec: jak dodać nowy moduł biznesowy

• 1
  Napisz modułcore/nazwa_modulu.py z funkcją wejściową def run(config, logger, **kwargs) -> dict. Loguj przez przekazany logger/callback — nie używaj print() w core/.
• 2
  Zarejestruj typW api/models.py::ModuleType (Enum) dodaj nowy wpis.
• 3
  Podłącz do dispatcheraW api/worker.py::MODULE_MAP — ModuleType.NOWY: nazwa_modulu.run. Specjalne call_params → blok w JobExecutor.
• 4
  CRON (opcjonalnie)Wpis w config/scheduler.json — scheduler przeładowuje się automatycznie, bez restartu.
• 5
  Dedykowany endpoint (opcjonalnie)Zamiast generycznego POST /api/jobs/{module} — dodaj w odpowiednim api/routes/*.py, zarejestruj router w api/server.py jeśli to nowy plik.
• 6
  Trwały stan między uruchomieniamiUżyj core.data_store.data_store, NIE osobnych plików JSON, chyba że moduł już historycznie tak robi.
• 7
  Zaktualizuj dokumentację od razuNie zostawiaj tego na później — ten projekt ma historię dokumentacji zostającej daleko w tyle za kodem.

Dostęp do danych — nie omijaj warstw

core/*.py  →  core.data_store.data_store  →  api/repository.py  →  api/database.py  →  SQLite

Integracje zewnętrzne — gdzie szukać kontraktów API

WordPress plugin — dodatkowa ostrożność

Deploy — dwie osobne procedury

Nie myl ich — pełne szczegóły w rozdziale Wdrożenie. W skrócie: backend Python (VPS/Docker) wymaga docker compose restart (plik .py) lub down && up -d (zmiana docker-compose.yml); plugin WordPress działa od razu po wgraniu FTP, ale wymaga bumpnięcia BOT_VERSION przy zmianach JS/CSS.

Zanim zaczniesz zmieniać kod — checklist

1. find core api -name "*.py" / Glob — zweryfikuj, że moduł faktycznie tak się nazywa.
2. Sprawdź, czy podobny wzorzec już istnieje gdzie indziej w core/ (47 modułów = 47 przykładów konwencji) zamiast wymyślać nowy styl.
3. Dla zmian w core/ — pamiętaj o lazy imports data_store i wymaganym logger= w WooCommerceClient.
4. Dla zmian w Allegro — sprawdź listę pułapek API w rozdziale Moduły Allegro.
5. Dla zmian w wordpress-plugin/ — zweryfikuj świeżość kopii (wc -l class-bot-admin.php ~3800 linii) i preferuj zmiany addytywne.
6. Po zmianie: python -m py_compile <plik>, a dla WordPress: php -l/policz nawiasy + node --check dla JS.
7. Zapytaj użytkownika przed każdą operacją nieodwracalną/współdzieloną (deploy na VPS, restart kontenera produkcyjnego, zmiany na erotivo.pl) — to działający sklep.

Słowniczek pojęć i skrótów